/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.handlers.events;

import com.hercules.android.receiver.AndroidReceiver;
import com.hercules.android.receiver.model.events.XREEvent;

/**
 * <p>
 * This interface defines the contract of raising an XREEvent either to the server or to the local receiver.
 * </p>
 *
 * <p>
 * <strong>Thread safety: </strong> The implementation of this interface must be thread-safe after initialization
 * </p>
 *
 * @author mekanizumu, jaindsonvs
 * @version 1.0
 */
public interface EventRaiser {
    /**
     * <p>
     * Raise a XRE event either to server or to local receiver (depending on the value of toServerOnly).
     * </p>
     *
     * @param toServerOnly
     *            this is true if the event should always be raised to server.
     * @param receiver
     *            the receiver used for raising the event.
     * @param event
     *            the event to raise.
     * @return true if the event is raised, false otherwise.
     * @throws EventRaisingException
     *             if any error occurs
     * @throws IllegalArgumentException
     *             if event is null; or receiver is null;
     */
    public boolean raiseEvent(XREEvent event, AndroidReceiver receiver, boolean toServerOnly)
        throws EventRaisingException;
}
